Skip to main content

Authentication

Introduction​

Welcome to our comprehensive guide on identity protocols and authentication for Nursa APIs. We support two primary identity protocols: OpenID Connect (OIDC) and therefore OAuth 2.0. Accessing Nursa APIs requires a JSON Web Token (JWT), ensuring secure and authenticated communication.

Auth Base URL​

Since Nursa provides two environments for third-party integrators, make sure to use the correct URL to connect to the Nursa Authorization Server:

Open ID Connect Discovery Endpoint​

If you are familiar with the OIDC protocol or are using an authentication tool that integrates with it, you may find this endpoint useful to get the Nursa Authorization Server OIDC metadata and smoothly integrate with it. The data returned by this endpoint is described in section 3 of the OpenID Connect Discovery.

GET https://auth.nursa.com/oidc/.well-known/openid-configuration

How to get a token​

To interact with our APIs, you need to generate a token. Follow the authorization documentation below to learn how to obtain your token.

Authentication

The authentication process involves two key endpoints: Authorization and Get Token. These endpoints facilitate secure token acquisition. For an in-depth understanding, refer to the official OpenID Connect documentation.

Get Token response explained​

The response object from the Get Token endpoint will look like this:

{
    "id_token": "eyJhbGciOiJSUzI1NiIsIn...KeneC4cJ-0O4dAA8FcCZIsaQ3jfTg",
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5c...uxQcwPoR20M92t2dbh8ScQ",
    "refresh_token": "v1.MXaZqGXvnP3...QUGSVqfviwV7p0MdFYSnb8M",
    "token_type": "Bearer",
    "scope": "openid profile email address phone role offline_access"
    "expires_in": 8640,
}
  • id_token: A JWT that contains user profile information used for authentication purposes.
  • access_token: A JWT used for authorization purposes like accessing protected resources.
  • refresh_token: An opaque string, not a JWT, used by the Refresh Token grant to obtain a new access_token when the current one expires.
  • token_type: Indicates the type of the token, which will always be Bearer.
  • scope: The request scope from the initial request to the Authorization or Get Token endpoint.
  • expires_in: Access token's lifespan in seconds.

Token claims​

Since the JWT token is a signed JSON Object, once the token is decoded it is possible to get the properties present in the payload part of that token, these object properties are called claims.

ID Token claims​

  • iss: (issuer) identifies the principal that issued the JWT, a valid token should have the value https://auth.nursa.com/.
  • aud: (audience) identifies the recipients that the JWT is intended for, the value of this claim will be your Client ID. It may be a string or an array of strings.
  • nonce: the same value provided on the initial Authentication Request, must be used to prevent replay attacks by checking if the value is the same as sent on the Authentication Request.
  • sid: (session ID) this value can be used later for logout.
  • sub: (subject) claim identifies the principal that is the subject of the JWT, this claim will normally carry the User ID.
  • name: the user's full name.
  • nickname: the user's nickname.
  • picture: the user's profile picture or avatar.
  • phone_number: the user's phone number.
  • email: the user's email.
  • role: the user's role in Nursa ecosystem, may be NURSE_USER or FACILITY_USER.
  • address: a nested object containing the user address information.
  • address.city: a property of the address object containing the user address city.
  • address.state: a property of the address object containing the user address state.
  • iat: (issued at) claim identifies the time the JWT was issued.
  • exp: (expiration time) identifies the expiration time on or after which the JWT MUST NOT be accepted for processing.

Access Token claims​

  • iss: (issuer) identifies the principal that issued the JWT, a valid token should have the value https://auth.nursa.com/.
  • sub: (subject) claim identifies the principal that is the subject of the JWT, this claim will normally carry the User ID.
  • role: the user's role in Nursa ecosystem, may be NURSE_USER or FACILITY_USER.
  • aud: (audience) identifies the recipients that the JWT is intended for, the value of this claim will be your Client ID. It may be a string or an array of strings.
  • azp: the party to which the ID Token was issued. This claim will contain your Application's Client ID.
  • scope: will contain the scope that was requested on Authentication Request and that was allowed by the user on the consent screen.
  • iat: (issued at) claim identifies the time the JWT was issued.
  • exp: (expiration time) identifies the expiration time on or after which the JWT MUST NOT be accepted for processing.

Tokens's Lifetime​

For security reasons, the access_token and refresh_token will have an expiration time.

  • access_token: will expire after one hour.
  • refresh_token: by default the refresh_token is a rotating code that will expire after 30 days and can only be used once. Every request to a new access_token will result in a new refresh_token too. If you need to extend the lifetime of a refresh token or use non-rotating tokens, please contact support.

Authorization Grants​

Nursa supports multiple grant types from the OAuth 2.0 protocol for obtaining tokens. You need to pick one that best fits your application context, take a look at the list of flows Nursa supports, and pick the right one.

Authorization Code Flow​

⚠️ Recommendation: This grant is recommended for Regular Web Applications where the code can be exchanged through a secure source like a back-end application since the Get Token request requires your secret credentials like the Application Client Secret.

The Authorization Code Flow (defined in OAuth 2.0 RFC 6749, section 4.1), involves exchanging an authorization code for a token.

How it works:

  1. User selects Login within application.
  2. Your front-end application redirects user to Nursa Authorization Server (/authorize endpoint).
  3. Nursa Authorization Server redirects user to login and authorization prompt.
  4. User authenticates using one of the configured login options, and may see a consent prompt listing the permissions Nursa will give to the application.
  5. Nursa Authorization Server redirects user back to your application with single-use authorization code.
  6. Your back-end Application sends authorization code, application's client ID, and client secret, to Nursa Authorization Server (/oauth/token endpoint).
  7. Nursa Authorization Server verifies authorization code, application's client ID, and application's credentials.
  8. Nursa Authorization Server responds with an ID token and access token (and optionally, a refresh token).
  9. Your Application can use the access token to call an API of the Nursa Resource Application.
  10. API responds with requested data.

How to implement it​

This flow requires two steps: Authorization and Get Token.

Step #1 - GET /authorize

You need to redirect the user to the login page, after the user authenticates the Nursa Auth Server will redirect back to your application using the URL provided in the redirect_uri parameter with a code parameter in this URL.

Request Parameters

Parameter nameParameter valueDescription
response_type requiredcodeIndicates to Nursa which OAuth 2.0 flow you want to use. Use code for Authorization Code Grant Flow.
client_id required{YOUR_CLIENT_ID}Your Application's Client ID
state recommended{RANDOM_GENERATED_TEXT}A string value that Nursa includes unchanged when redirecting back to the client application. This value must be used by the application to prevent CSRF attacks.
nonce recommended{NONCE}A string value which will be included unchanged in the ID Token response from Nursa, used to prevent token replay attacks.
redirect_uri{YOUR_APPLICATION_URI}The URL to which Nursa will redirect the user after authorization has been granted by the user.
audiencehttps://public-api.prod.nursa.com/The unique identifier of the target API you want to access.
scope{LIST_OF_SCOPES}The scopes which you want to request authorization for. These must be separated by a space. You can request any of the scopes supported by Nursa.
promptloginIf you want to force the user to always provide the credentials while signing in use login, otherwise user will automatically be authenticated if they are already logged in.
screen_hintsignupOnly use this parameter to display the signup page to user instead of the login feature.

Notes

  • Include offline_access to the scope request parameter to get a refresh token from POST /oauth/token.
  • The redirect_uri value must be specified as a valid callback URL under your Application's Settings on Developer Portal.

Request example:

GET https://auth.nursa.com/oidc/authorize
    ?response_type=code
    &client_id=YOUR_CLIENT_ID
    &redirect_uri=https://my-application.com/auth/callback
    &state=STATE
    &nonce=NONCE
    &audience=https://public-api.prod.nursa.com/
    &scope=profile email name role marketplace:read marketplace:write

Response example:

HTTP/1.1 302 Found
Location: https://my-application.com/auth/callback?code=AUTHORIZATION_CODE&state=STATE

Step #2 - POST /oauth/token

You need to grab the Authorization Code from the code parameter from the previous request and exchange it for a token by calling the /oauth/token endpoint. Since this request uses the Client Secret it must not be performed from an insecure context like a web browser.

Request Parameters

Parameter nameParameter valueDescription
grant_type requiredauthorization_codeDenotes the flow you are using. For Authorization Code, use authorization_code.
client_id required{YOUR_CLIENT_ID}Your Application's Client ID
client_secret required{YOUR_CLIENT_SECRET}Your application's Client Secret.
code required{AUTHORIZATION_CODE}The Authorization Code received from the initial /authorize call.
redirect_uri{your_application_uri}This is required only if it was set at the GET /authorize endpoint. The values from /authorize must match the value you set at /oauth/token.

Request Example:

POST https://auth.nursa.com/oidc/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=code&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&code=AUTHORIZATION_CODE&redirect_uri=https://my-application.com/auth/callback

Response Example:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "id_token":"eyJ0XAi...4faeEoQ",
  "access_token":"eyJz93a...k4laUWw",
  "refresh_token":"GEbRxBN...edjnXbL",
  "token_type":"Bearer",
  "scope": "profile email name role marketplace:read marketplace:write"
  "expires_in": 86400
}

Authorization Code Flow With PKCE​

💡 Recommendation: This grant is designed for public apps like native or single-page-applications since these applications can not securely store the Client Secret.

Authorization Code Flow with Proof Key for Code Exchange (PKCE) is the OAuth 2.0 (defined in OAuth 2.0 RFC 7636) grant that mobile apps utilize to access an API. Before starting with this flow, you need to generate and store a code_verifier, and using that, generate a code_challenge that will be sent in the authorization request.

💡 Tip: You may want to use an existing tool to generate the codes since it would facilitate your development process.

How it works:

  1. User selects Login within application.
  2. Your front-end application generates a code_verifier and a code_challenge. The definition on how to generate it is found under the section 4.1 of the OAuth 2.0 RFC 7636.
  3. Your front-end application redirects user to Nursa Authorization Server (/authorize endpoint) sending the code_challenge.
  4. Nursa Authorization Server redirects user to login and authorization prompt.
  5. User authenticates using one of the configured login options, and may see a consent prompt listing the permissions Nursa will give to the application.
  6. Nursa Authorization Server redirects user back to your application with single-use authorization code.
  7. Your front-end application sends authorization code, code_verifier, and application's client ID to Nursa Authorization Server (/oauth/token endpoint).
  8. Nursa Authorization Server verifies authorization code, code_verifier, and application's client ID.
  9. Nursa Authorization Server responds with an ID token and access token (and optionally, a refresh token).
  10. Your Application can use the access token to call an API of the Nursa Resource Application.
  11. API responds with requested data.

How to implement it​

This flow requires two steps: Authorization and Get Token.

Step #1 - GET /authorize

You need to redirect the user to the login page, after user authenticates the Nursa Auth Server will redirect back to your application with a code parameter in the URL.

Request Parameters

Parameter nameParameter valueDescription
response_type requiredcodeIndicates to Nursa which OAuth 2.0 flow you want to use. Use code for Authorization Code Grant Flow.
client_id required{YOUR_CLIENT_ID}Your Application's Client ID
code_challenge required{CODE_CHALLENGE}Generated challenge from the code_verifier. See sections 4.1 and 4.2 of the OAuth 2.0 RFC 7636.
code_challenge_method requiredS256Method used to generate the challenge. The PKCE spec defines two methods, S256 and plain, however, Nursa supports only S256 since the latter is discouraged.
state recommended{RANDOM_GENERATED_TEXT}An opaque value the application adds to the initial request that Nursa includes when redirecting back to the application. This value must be used by the application to prevent CSRF attacks.
redirect_uri{YOUR_APPLICATION_URI}The URL to which Nursa will redirect the browser after authorization has been granted by the user.
audiencehttps://public-api.prod.nursa.com/The unique identifier of the target API you want to access.
scope{LIST_OF_SCOPES}The scopes which you want to request authorization for. These must be separated by a space. You can request any of the scopes supported by Nursa.
promptloginIf you want to force the user to always provide the credentials use login otherwise user will automatically authenticated if they are already logged in.
screen_hintsignupOnly use this parameter to display the signup page to user instead of the login feature.

Notes

  • Include offline_access to the scope request parameter to get a refresh token from POST /oauth/token.
  • The redirect_uri value must be specified as a valid callback URL under your Application's Settings on Developer Portal.

Request example:

GET https://auth.nursa.com/oidc/authorize
    ?response_type=code
    &client_id=YOUR_CLIENT_ID
    &code_challenge=CODE_CHALLENGE
    &code_challenge_method=S256
    &redirect_uri=https://my-application.com/auth/callback
    &state=STATE
    &audience=https://public-api.prod.nursa.com/
    &scope=profile email name role marketplace:read marketplace:write

Response example:

HTTP/1.1 302 Found
Location: https://my-application.com/auth/callback?code=AUTHORIZATION_CODE&state=STATE

Step #2 - POST /oauth/token

You need to grab the Authorization Code from the code parameter from the previous request and exchange it for a token by calling the /oauth/token endpoint. This request will require the code_verifier generated by the previous step.

Request Parameters

Parameter nameParameter valueDescription
grant_type requiredauthorization_codeDenotes the flow you are using. For Authorization Code (PKCE), use authorization_code.
client_id required{YOUR_CLIENT_ID}Your Application's Client ID
code required{AUTHORIZATION_CODE}The Authorization Code received from the initial /authorize call.
code_verifier required{CODE_VERIFIER}Cryptographically random key that was used to generate the code_challenge passed to /authorize. See sections 4.1 and 4.2 of the OAuth 2.0 RFC 7636.
redirect_uri{your_application_uri}This is required only if it was set at the GET /authorize endpoint. The values from /authorize must match the value you set at /oauth/token.

Request Example:

POST https://auth.nursa.com/oidc/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=code&client_id=YOUR_CLIENT_ID&code_verifier=CODE_VERIFIER&code=AUTHORIZATION_CODE&redirect_uri=https://my-application.com/auth/callback

Response Example:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "id_token":"eyJ0XAi...4faeEoQ",
  "access_token":"eyJz93a...k4laUWw",
  "refresh_token":"GEbRxBN...edjnXbL",
  "token_type":"Bearer",
  "scope": "profile email name role marketplace:read marketplace:write"
  "expires_in": 86400
}

Resource Owner Password Flow​

Though we do not recommend it, highly-trusted applications can use the Resource Owner Password Flow (defined in OAuth 2.0 RFC 6749, section 4.3), which requests that users provide credentials (username and password), typically using an interactive form. Because credentials are sent to the backend and can be stored for future use before being exchanged for an Access Token, it is imperative that the application is absolutely trusted with this information.

Even if this condition is met, the Resource Owner Password Flow should only be used when redirect-based flows (like the Authorization Code Flow) cannot be used.

How it works:

  1. The user clicks Login within the application and enters their credentials.
  2. Your application forwards the user's credentials to Nursa Authorization Server (/oauth/token endpoint).
  3. Nursa Authorization Server validates the credentials.
  4. Nursa Authorization Server responds with an Access Token (and optionally, a Refresh Token).
  5. Your application can use the Access Token to call an API to access information about the user.
  6. The API responds with requested data.

How to implement it​

This flow only requires a single request to the /oauth/token endpoint

POST /oauth/token

You need to grab the Authorization Code from the code parameter from the previous request and exchange it for a token by calling this endpoint. This request will need the code_verifier generated by the previous step.

Request Parameters

Parameter nameParameter valueDescription
grant_type requiredpasswordDenotes the flow you are using. For Resource Owner Password use password.
username required{USERNAME}User's email or username also known as Resource Owner's identifier.
password required{PASSWORD}User's password also known as Resource Owner's secret.
client_id required{YOUR_CLIENT_ID}Your Application's Client ID
client_secret{YOUR_CLIENT_SECRET}Required when the Token Endpoint Authentication Method is set to Post or Basic, this configuration will depend on your agreement with Nursa.
audiencehttps://public-api.prod.nursa.com/The unique identifier of the target API you want to access.
scope{LIST_OF_SCOPES}The scopes which you want to request authorization for. These must be separated by a space. You can request any of the scopes supported by Nursa.

Request Example:

POST https://auth.nursa.com/oidc/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=password&username=USERNAME&password=PASSWORD&audience=https://public-api.prod.nursa.com/&scope=LIST_OF_SCOPES&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET

Response Example:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "access_token":"eyJz93a...k4laUWw",
  "token_type":"Bearer",
  "scope": "profile email name role marketplace:read marketplace:write"
  "expires_in": 86400
}

Implicit Flow​

⚠️ Note: Nursa does not recommend the use of this flow to obtain an access_token. Use this flow for login-only (ID Token) use cases, if you need an Access Token to call an API use the Authorization Code Flow with PKCE.

You can use OpenID Connect (OIDC) with many different flows to achieve web sign-in for a traditional web app. In one common flow, you obtain an ID token using authorization code flow performed by the app backend. This method is effective and robust, however, it requires your web app to obtain and manage a secret. You can avoid that burden if all you want to do is implement sign-in and you don’t need to obtain access tokens for invoking APIs.

Implicit Flow with Form Post flow uses OIDC to implement web sign-in that is very similar to the way SAML and WS-Federation operates. The web app requests and obtains tokens through the front channel, without the need for secrets or extra backend calls. With this method, you don’t need to obtain, maintain, use, and protect a secret in your application.

How it works:

  1. The user clicks Login in the app.
  2. Your front-end application must redirect the user to the Nursa Authorization Server (/authorize endpoint) passing along a response_type parameter of id_token that indicates the type of requested credential. It also passes along a response_mode parameter of form_post to ensure security.
  3. Nursa Authorization Server redirects the user to the login and authorization prompt.
  4. The user authenticates using one of the configured login options and may see a consent page listing the permissions Nursa will give to the app.
  5. Nursa Authorization Server redirects the user back to the app with an ID Token.

How to implement it​

This flow only requires a forward to the /authorize endpoint.

GET /authorize

You need to redirect the user to the login page, after user authenticates the Nursa Auth Server will redirect back to your application with a token, an id_token, or both parameters in the URL depending on what you requested.

Request Parameters

Parameter nameParameter valueDescription
response_type requiredtoken OR id_token OR token id_tokenThis will specify the type of token you will receive at the end of the flow. Use token to get only an Access Token, id_token to get only an ID token (if you don't plan on accessing an API), or token id_token to get both an ID token and an Access Token.
client_id required{YOUR_CLIENT_ID}Your Application's Client ID
state recommended{RANDOM_GENERATED_TEXT}An opaque value the application adds to the initial request that Nursa includes when redirecting back to the application. This value must be used by the application to prevent CSRF attacks.
nonce recommended{NONCE}A string value which will be included in the ID token response from Nursa, used to prevent token replay attacks. It is required for response_type=token id_token.
redirect_uri{YOUR_APPLICATION_URI}The URL to which Nursa will redirect the browser after authorization has been granted by the user.
response_modefragment OR form_postDefines the way you want to receive the token. Default value is form_post where Nursa Authorization Server will send a POST request with a application/x-www-form-urlencoded object to the URL informed on redirect_uri param. If fragment is informed then the Nursa Authorization Server will send the token in the fragment (#) of the URL as a GET request. Notice that you can not receive the token as query parameters.
audiencehttps://public-api.prod.nursa.com/The unique identifier of the target API you want to access.
scope{LIST_OF_SCOPES}The scopes which you want to request authorization for. These must be separated by a space. You can request any of the scopes supported by Nursa.
promptloginIf you want to force the user to always provide the credentials use login otherwise user will automatically authenticated if they are already logged in.

Notes

  • The redirect_uri value must be specified as a valid callback URL under your Application's Settings on Developer Portal.
  • The Implicit Grant does not support the issuance of Refresh Tokens.

Request example (Form Post):

GET https://auth.nursa.com/oidc/authorize
    ?response_type=token id_token
    &response_mode=form_post
    &client_id=YOUR_CLIENT_ID
    &redirect_uri=https://my-application.com/auth/callback
    &state=STATE
    &nonce=NONCE
    &audience=https://public-api.prod.nursa.com/
    &scope=profile email name role marketplace:read marketplace:write

Response example (Form Post):

⚠️ Notice that in this scenario you don't receive a response, instead Nursa Authorization Server will POST a request to the redirect_uri provided on the /authorize endpoint. This POST is performed in the web browser so it will look like a redirect to the end user but keep in mind that you need to handle an HTTP POST.

POST https://my-application.com/auth/callback
Content-Type: application/x-www-form-urlencoded

id_token=eyJ0XAi...4faeEoQ&access_token=eyJz93a...k4laUWw&token_type=Bearer&state=STATE&scope=profile email name role marketplace:read marketplace:write&expires_in=86400

Request example (Fragment):

GET https://auth.nursa.com/oidc/authorize
    ?response_type=token id_token
    &response_mode=fragment
    &client_id=YOUR_CLIENT_ID
    &redirect_uri=https://my-application.com/auth/callback
    &state=STATE
    &nonce=NONCE
    &audience=https://public-api.prod.nursa.com/
    &scope=profile email name role marketplace:read marketplace:write

Response example (Fragment):

HTTP/1.1 302 Found
Location: https://my-application.com/auth/callback#access_token=TOKEN&state=STATE&token_type=TYPE&expires_in=SECONDS

⚠️ Notice the # and not a ? before the parameters.

Refresh Token​

Refresh tokens are used to request a new access token and/or ID token for a user without requiring them to re-authenticate. Refresh Token grant is defined in OAuth 2.0 RFC 6749, section 6. You need to store the refresh_token received on previous response to be able to use it for the following requests.

Typically, you should request a new access token before the previous one expires (to avoid any service interruption), but not every time you call an API, as token exchanges are subject to our Rate Limiting Policy.

You may also use a refresh token to request a new ID token for a user, and should do so if you need to refresh the claims within the ID token.

How it works

  1. Your application authorizes the user with the Authorization Code Flow and stores the given refresh_token.
  2. Your application calls the /oauth/token endpoint of Nursa Authorization Server.
  3. Nursa Authorization Server validates that the Refresh Token is still valid.
  4. Nursa Authorization Server returns a new set of tokens (id_token, access_token, refresh_token).

Notes

  • A Refresh Token lifetime will expire after 30 days, after that time your application will need to request the user to reauthenticate because that Refresh Token will not be allowed to generate a new one. If you want to extend the Refresh Token lifetime, contact the Nursa Support.
  • Nursa uses Rotating Refresh Tokens, which means that every time you call the Refresh Token endpoint your application will receive a new string as refresh_token and the previous one can no longer be used. If you need static Refresh Tokens contact Nursa Support.

How to implement it​

This grant only requires a single request to the /oauth/token and can be performed multiple times until the Refresh Token expires.

POST /oauth/token

You need to use the refresh_token received in previous steps.

Request Parameters

Parameter nameParameter valueDescription
grant_type requiredrefresh_tokenDenotes the flow you are using. To refresh a token, use refresh_token.
client_id required{YOUR_CLIENT_ID}Your Application's Client ID
client_secret{YOUR_CLIENT_SECRET}Required when the Token Endpoint Authentication Method is set to Post or Basic, this configuration will depend on your agreement with Nursa.
refresh_token required{REFRESH_TOKEN}The refresh token obtained in the previous step.
scope{LIST_OF_SCOPES}A space-delimited list of requested scope permissions. If not sent, the original scopes will be used; otherwise, you can request a reduced set of scopes. Note that this must be URL encoded.

Request Example:

POST https://auth.nursa.com/oidc/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&client_id=YOUR_CLIENT_ID&refresh_token=REFRESH_TOKEN

Response Example:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "id_token":"eyJ0XAi...4faeEoQ",
  "access_token":"eyJz93a...k4laUWw",
  "refresh_token":"GEbRxBN...edjnXbL",
  "token_type":"Bearer",
  "scope": "profile email name role marketplace:read marketplace:write"
  "expires_in": 86400
}

Client Credentials Flow​

The Client Credentials Flow (defined in OAuth 2.0 RFC 6749, section 4.4) involves an application exchanging its application credentials, such as client ID and client secret, for an access token.

This flow is best suited for Machine-to-Machine (M2M) applications, such as CLIs, daemons, or backend services because the system must authenticate and authorize the application instead of a user. After all, the token generated by this grant does not hold any user information, and the sub claim will carry the application's client ID prefixed by the marker app: e.g. app:d7q8GeITFv7XjjQpwuGeZt2hwkHOgfcT.

How it works

  1. Application sends application's credentials to the Nursa Authorization Server.
  2. Nursa Authorization Server validates application's credentials.
  3. Nursa Authorization Server responds with an access token.
  4. Application can use the access token to call an API on behalf of itself. For more information on this process, see Validate JSON Web Tokens.
  5. API responds with requested data.

How to implement it​

This grant uses the /oauth/token that should be called from a Machine-to-Machine context.

POST /oauth/token

You need to grab the Client ID and Client Secret of your Application from Nursa Developer Portal.

Request Parameters

Parameter nameParameter valueDescription
grant_type requiredclient_credentialsDenotes the flow you are using. For Client Credentials use client_credentials.
client_id required{YOUR_CLIENT_ID}Your Application's Client ID
client_secret required{YOUR_CLIENT_SECRET}Your application's Client Secret.
audience requiredhttps://public-api.prod.nursa.com/ OR https://public-api.sandbox.nursa.com/The unique identifier of the target API you want to access.

Request Example:

POST https://auth.nursa.com/oidc/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&audience=https://public-api.prod.nursa.com/

Response Example:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "access_token":"eyJz93a...k4laUWw",
  "token_type":"Bearer",
  "scope": "profile email name role marketplace:read marketplace:write"
  "expires_in": 86400
}

Errors:

Grant type now allowed

{
    "error": "unauthorized_client",
    "error_description": "Grant type 'client_credentials' not allowed for the client."
}

To prevent abusive usage from malicious agents, by default, the client_credentials grant type is not allowed for applications, the integrator needs to contact the Nursa team to enable that option for the application.

Notes

  • Will not return an id_token since it is an Application authentication and there is no user involved.
  • Will not return a refresh_token since a new Access Token can simply generated by calling this endpoint again.

UserInfo Endpoint​

The UserInfo endpoint is a OAuth 2.0 Protected Resource that returns Claims about the authenticated End-User. The OIDC definition of this endpoint is found in section 5.3 of the Open ID Connect Core.

To access this endpoint you need to provide the access_token obtained on Authentication step.

How it works

  1. An Access Token must be previously obtained by forwarding the user through one of the Authorization grants.
  2. With the Access Token, your application can call this endpoint.
  3. Nursa Authorization Server will return the data that was previously allowed by the user.

How to implement it​

After implementing the authentication flow, call this endpoint with the access_token in the Authorization Header.

GET /oidc/userinfo

Request Example:

GET https://auth.nursa.com/oidc/userinfo
Authorization: Bearer eyJhbGciOiJSUzI1Ni...CIsImtpZCI6ImI0NTA0Z

Response Example:

{
    "sub": "3YcMhdFIsdX3S4eFD5W5PACo9gy2",
    "name": "John Doe",
    "nickname": "John",
    "picture": "https://myavatar.com/3YcMhdFIsdX3S4eFD5W5PACo9gy2",
    "phone_number": "+10000000000",
    "email": "john.doe@nursa.com",
    "role": "FACILITY_USER",
    "address": {
        "city": "Salt Lake City",
        "state": "UT"
    }
}

Notes

  • The claims (properties) returned by this resource will be based on scopes requested during the Authentication step and allowed by the user.

Logout​

This endpoint is used to terminate a user's session on Nursa Authorization Server. When implementing the logout on your application it is recommended that you also end the user's session on Nursa side, to do that you can use the /oidc/logout endpoint.

How it works

💡 Note: step 1 could be the last step instead, it depends on what fits better your application needs.

  1. Finish the user from your application
  2. Forward the user to Nursa Authorization Server /logout endpoint informing post_logout_redirect_uri parameter
  3. Nursa Authorization Server will end the user session
  4. Nursa Authorization Server will redirect the user to the URL informed on post_logout_redirect_uri parameter

How to implement it​

You need to forward the user to the /oidc/logout endpoint.

GET /oidc/logout

Request Parameters

Parameter nameParameter valueDescription
id_token_hint recommended{ID_TOKEN}Previously issued ID Token for the user. This is used to indicate which user to log out. If not provided, or invalid, user may be requested to consent to logout.
logout_hint{SESSION_ID}Optional sid (session ID) value to indicate which user to log out. Should be provided when id_token_hint is not available. The sid can be found on id_token claims.
client_id{YOUR_CLIENT_ID}The client_id of your application.
post_logout_redirect_uri{LOGOUT_URL}URL to redirect the user after the logout. Please request that Nursa Support allow this URL for your application. If not provided, user will be presented with a Nursa UI saying the logout was successful.
state{STATE}An opaque value the applications adds to the initial request that the authorization server includes when redirecting the back to the post_logout_redirect_uri.

Request Example:

POST https://auth.nursa.com/oidc/logout
    &client_id=YOUR_CLIENT_ID
    &id_token_hint=eyJhbGciOiJSUzI1Ni...CIsImtpZCI6ImI0NTA0Z
    &post_logout_redirect_uri=https://my-application.com/auth/logout
    &state=STATE

Response Example:

HTTP/1.1 302 Found
Location: https://my-application.com/auth/logout?state=STATE